home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / il / ilRoiIter.z / ilRoiIter
Encoding:
Text File  |  2002-10-03  |  9.8 KB  |  265 lines
  1.  
  2.  
  3.  
  4. iiiillllRRRRooooiiiiIIIItttteeeerrrr((((3333))))       IIIImmmmaaaaggggeeeeVVVViiiissssiiiioooonnnn LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll       iiiillllRRRRooooiiiiIIIItttteeeerrrr((((3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      iiiillllRRRRooooiiiiIIIItttteeeerrrr - class for cycling through run lengths in an ROI
  10.  
  11. IIIINNNNHHHHEEEERRRRIIIITTTTSSSS FFFFRRRROOOOMMMM
  12.      This is a base class and therefore has no inheritance.
  13.  
  14. HHHHEEEEAAAADDDDEEEERRRR FFFFIIIILLLLEEEE
  15.      #include <il/ilRoiIter.h>
  16.  
  17. CCCCLLLLAAAASSSSSSSS DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  18.      This abstract class provides functions that can be used to iterate or
  19.      cycle through a region-of-interest, or ROI.  They can be used within a
  20.      specified rectangle (clip box) or an entire image. Once an ROI has been
  21.      created (see the ilRectRoi and ilImgRoi man pages), an iterator can be
  22.      constructed that binds the ROI to an image at a specified offset.
  23.  
  24.      An ilRoiIter object provides functions to cycle through runs of valid
  25.      and/or invalid data:  nnnneeeexxxxtttt() and nnnneeeexxxxttttMMMMaaaattttcccchhhh().  Functions are provided
  26.      that return the starting location and lengths of the run lengths:
  27.      ggggeeeettttXXXX(), ggggeeeettttYYYY(), ggggeeeettttZZZZ() and ggggeeeettttLLLLeeeennnn().
  28.  
  29.      Once an ilRoiIter object has been created, it may be used to step through
  30.      the valid and/or invalid regions defined by the ROI.
  31.  
  32.      EEEExxxxaaaammmmpppplllleeee ooooffff uuuusssseeee
  33.  
  34.      The following example demonstrates how to use an ROI iterator:
  35.  
  36.           //create  a rectangular ROI of size 50 x 60
  37.           ilRectRoi myroi(50, 60, 1);
  38.  
  39.           //set ROI attributes
  40.  
  41.           ilImage *img = ilOpenImgFile ("myImage", "r");
  42.  
  43.           // create an iterator, mapping the ROI to the image at offset (10,20)
  44.           ilRoiIter* iter;
  45.           iflXYZint off(10, 20, 0);
  46.           myroi.createIter(NULL, &iter, img, 0, 0, 0, 100, 100, 1, &off);
  47.  
  48.           // for each valid region...
  49.           while (iter->nextMatch()) {
  50.               int xbegin = iter->getX();
  51.               int ybegin = iter->getY();
  52.               int len = iter->getLen();
  53.  
  54.               // do some processing
  55.  
  56.           }
  57.  
  58.      DDDDeeeerrrriiiivvvviiiinnnngggg ffffrrrroooommmm iiiillllRRRRooooiiiiIIIItttteeeerrrr
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. iiiillllRRRRooooiiiiIIIItttteeeerrrr((((3333))))       IIIImmmmaaaaggggeeeeVVVViiiissssiiiioooonnnn LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll       iiiillllRRRRooooiiiiIIIItttteeeerrrr((((3333))))
  71.  
  72.  
  73.  
  74.      Each derived class of ilRoi requires a derived ilRoiIter class that
  75.      iterates over the run-lengths of the ROI.  Deriving a new class requires
  76.      only that the pure virtual nnnneeeexxxxtttt() be defined to advance to the next
  77.      segment of the ROI.  An ROI segment is a length of pixels, consecutive in
  78.      the X dimension, that lies entirely inside or entirely outside the valid
  79.      region.  The iterator should advance in X first, then Y, and finally Z
  80.      (for 3D ROI's).  The protected method uuuuppppddddaaaatttteeee() performs some common
  81.      post-processing that all iterators will need to do.  A typical recipe for
  82.      nnnneeeexxxxtttt() is:
  83.  
  84.           check if done; if so return FALSE;
  85.           set _l_a_s_t = _p_o_s; (remember where this segment started)
  86.           set _f_o_r_e flag based on first pixel in segment;
  87.                (foreground/valid -> TRUE; background/invalid -> FALSE)
  88.           scan pixels while foreground state remains the same;
  89.           call uuuuppppddddaaaatttteeee();
  90.           return TRUE;
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. iiiillllRRRRooooiiiiIIIItttteeeerrrr((((3333))))       IIIImmmmaaaaggggeeeeVVVViiiissssiiiioooonnnn LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll       iiiillllRRRRooooiiiiIIIItttteeeerrrr((((3333))))
  137.  
  138.  
  139.  
  140. CCCCLLLLAAAASSSSSSSS MMMMEEEEMMMMBBBBEEEERRRR FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN SSSSUUUUMMMMMMMMAAAARRRRYYYY
  141.      CCCCoooonnnnssssttttrrrruuuuccccttttoooorrrr
  142.  
  143.           ilRoiIter(ilRoi *roi, ilRoiMap *map)              protected
  144.  
  145.  
  146.      GGGGeeeetttt rrrruuuunnnn lllleeeennnnggggtttthhhhssss,,,, ssssttttaaaarrrrttttiiiinnnngggg llllooooccccaaaattttiiiioooonnnn
  147.  
  148.           int getX()
  149.           int getY()
  150.           int getLen()
  151.  
  152.  
  153.      SSSStttteeeepppp ttttoooo nnnneeeexxxxtttt RRRROOOOIIII rrrreeeeggggiiiioooonnnn
  154.  
  155.           int next()
  156.           int nextMatch(int foreground=TRUE)
  157.  
  158.  
  159. FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNNSSSS
  160.      iiiillllRRRRooooiiiiIIIItttteeeerrrr(((())))
  161.  
  162.           ilRoiIter(ilRoi *roi, ilImage* img)
  163.  
  164.  
  165.           The constructor takes a pointer to an ROI object, _r_o_i, and a pointer
  166.           to an ilImage object, _i_m_g. The constructor is protected, since it
  167.           should only be called from derived class constructors.
  168.  
  169.      ggggeeeettttLLLLeeeennnn(((())))
  170.  
  171.           int getLen()
  172.  
  173.  
  174.           Returns length of the current run of valid or invalid data.
  175.           Typically, this function is called after nnnneeeexxxxtttt() or nnnneeeexxxxttttMMMMaaaattttcccchhhh() is
  176.           called.
  177.  
  178.      ggggeeeettttXXXX(((())))
  179.  
  180.           int getX()
  181.  
  182.  
  183.           Returns the x coordinate of the starting location of the run length.
  184.           Typically, this function is called after nnnneeeexxxxtttt() or nnnneeeexxxxttttMMMMaaaattttcccchhhh() is
  185.           called.  This x coordinate is computed in the orientation specified
  186.           in the target image.
  187.  
  188.      ggggeeeettttYYYY(((())))
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. iiiillllRRRRooooiiiiIIIItttteeeerrrr((((3333))))       IIIImmmmaaaaggggeeeeVVVViiiissssiiiioooonnnn LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll       iiiillllRRRRooooiiiiIIIItttteeeerrrr((((3333))))
  203.  
  204.  
  205.  
  206.           int getY()
  207.  
  208.  
  209.           Returns the y coordinate of the starting location of the run length.
  210.           Typically, this function is called after nnnneeeexxxxtttt() or nnnneeeexxxxttttMMMMaaaattttcccchhhh() is
  211.           called.  This y coordinate is computed in the orientation specified
  212.           in the target image.
  213.  
  214.      ggggeeeettttZZZZ(((())))
  215.  
  216.           int getZ()
  217.  
  218.  
  219.           Returns the z coordinate of the starting location of the run length.
  220.           Typically, this function is called after nnnneeeexxxxtttt() or nnnneeeexxxxttttMMMMaaaattttcccchhhh() is
  221.           called.  The z coordinate is only useful when dealing with a 3-
  222.           dimensional region of interest; in the 2-D case, it can be ignored.
  223.  
  224.      ggggeeeettttVVVVaaaalllluuuueeee(((())))
  225.  
  226.           float getValue()
  227.  
  228.  
  229.           Returns the value of the region; this is currently only useful when
  230.           using an image-mapped ROI (ilImgRoi) in "run-length" mode; see the
  231.           man page for ilImgRoi for more details on run-length ROI processing.
  232.  
  233.      nnnneeeexxxxtttt(((())))
  234.  
  235.           int next()
  236.  
  237.  
  238.           This function returns TRUE if a valid or invalid region is found;
  239.           false if the iterator has completely scanned the specified area.
  240.  
  241.      nnnneeeexxxxttttMMMMaaaattttcccchhhh(((())))
  242.  
  243.           int nextMatch(int foreground=TRUE)
  244.  
  245.  
  246.           This function returns TRUE if a region matching the specified type
  247.           is found; false otherwise.  If the _f_o_r_e_g_r_o_u_n_d paramater is TRUE,
  248.           then only a foreground, or valid, region will be returned.  If
  249.           FALSE, then only a background, or invalid, region will be returned.
  250.  
  251. IIIINNNNHHHHEEEERRRRIIIITTTTEEEEDDDD MMMMEEEEMMMMBBBBEEEERRRR FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNNSSSS
  252. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  253.      ilImgRoi, ilRectRoi, ilRoi
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.